Skip to main content

SuperHote

How to authenticate the integration​

We'll use a test app, Acme AI, to show how an end-user can authenticate the integration between SuperHote and Acme AI.

  1. Go to Settings > Integrations section within Acme AI app.

  2. Among the list of Integrations, click on SuperHote's logo and you will be redirected to the Authentication Screen as shown below.

    superhote auth 1

  3. Now switch over to your SuperHote account in a new tab. In the left sidebar, go to Platforms and Integrations > SuperHote V2 API. Click on 'Create API key'.

    superhote auth 2

    Make sure to grant at least the following permissions:

    • public-api:rentals.read
    • public-api:reservations.read
    • public-api:messages.read (if you need conversation reads)
    • public-api:messages.write (if you need to send messages)
    • public-api:webhooks.manage (if you need real-time webhooks)

    Copy the generated API key.

  4. Paste it back on your Authentication Screen (from Point 2) and Click on 'Connect'. You will see a message box that shows you've successfully authenticated the integration. You will be redirected back to Acme app now.

How to set up Real-time webhooks​

  1. Go to the SuperHote account's section within Calry ('Accounts > SuperHote account > Webhooks'). Type in the name, URL where you'd like to receive the webhooks and check off the events you'd like to subscribe to. Click on 'Create'.

    superhote auth 3

  2. Or if you're already using the Create Webhook API to subscribe to webhooks, create the webhook for the SuperHote account through the API instead.

  3. That's it! Calry registers the webhook in SuperHote automatically using the account's API key. You will start receiving webhooks from this account now.

The following events are supported:

Calry eventSent when
reservation.createdA reservation is created in SuperHote.
reservation.updatedA reservation is modified or cancelled. Cancellations are sent as reservation.updated with status CANCELLED; reservation.deleted is not sent.
conversation.updatedA guest sends a message, or the host sends a message from SuperHote. senderType is Guest or Owner respectively.

Notes:

  • Step 1 or 2 has to be done by Acme AI, the company integrated with Calry. The end-customer only needs to grant the public-api:webhooks.manage permission when creating the API key (see How to authenticate the integration). The API key must stay active while webhooks are in use.
  • SuperHote signs every delivery, and Calry verifies the signature before forwarding it to you. SuperHote returns the signing secret only once, when the webhook is created, and Calry stores it. To change or remove the webhook, update or delete it in Calry; updating it re-registers the webhook in SuperHote.
  • Webhooks can be delivered more than once, so make your handler idempotent:
    • A retried delivery keeps the same hook.id. Skip events whose hook.id you have already processed.
    • SuperHote can also send the same message twice as separate deliveries, each with a different hook.id. For conversation.updated, deduplicate on the message id in record.messages instead.
  • SuperHote allows at most 10 webhooks per account.

If you have any questions or need help, don't hesitate to reach out at mail@calry.app.